Skip to main content

שירות תו חנייה - מפרט טכני

1. סיכום מנהלים​

שירות תו חנייה הוא חלק ממערכת מוני service המאפשרת לדיירים להגיש בקשות לתווי חנייה, לבדוק תווי חנייה פעילים ולקבל מידע על סוגי תווי חנייה זמינים ברשות המקומית. השירות מטפל בתהליכי הגשת בקשות, אימות נתונים, והעברת מידע בין המערכת לספקיות חיצוניות.

השירות פועל כחלק ממערכת microservices וממשק עם:

  • מערכת הרשויות המקומיות
  • ספקיות חיצוניות לניהול תווי חנייה
  • מערכת Directus לבדיקות דמו
  • מערכת אימות OAuth2

זרימת עבודה פשוטה:

  1. האזרח נכנס לממשק תווי חנייה, בוחר פעולה (הגשת בקשה/בדיקת תווי פעילים/סוגי תווי זמינים)
  2. מוני service קולט את הנתונים וממיר אותם
  3. מוני service פונה לספק בשביל קבלת מידע או הגשת בקשה
  4. מוני service מעבד את המידע ומארגן אותו
  5. מוני service מחזיר לאזרח מידע מפורט על תווי החנייה

2. תכונות עיקריות​

  • הגשת בקשות תו חנייה: טופס מקוון להגשת בקשה לתו חנייה
  • בדיקת תווי חנייה פעילים: הצגת תווי חנייה פעילים לפי מספר זהות ורשות מקומית
  • קבלת סוגי תווי חנייה: רשימת סוגי תווי חנייה זמינים ברשות המקומית
  • אימות נתונים: בדיקת תקינות פרטי הרכב והנהג
  • ממשק עם ספקיות חיצוניות: העברת נתונים לספקיות מוניציפליות
  • ניהול קבצים: העלאת מסמכים רלוונטיים
  • בדיקת Directus: אימות נתונים מול שרת דמו

3. מדריך שימוש מהיר​

3.1 הגשת בקשה לתו חנייה​

  1. מלא את פרטי הנהג (שם, תעודת זהות, כתובת, טלפון, אימייל)
  2. הזן פרטי הרכב (מספר רכב, סוג רכב, שנת ייצור)
  3. בחר סוג תו חנייה מבוקש
  4. העלה מסמכים רלוונטיים (רישיון נהיגה, אישור רכב)
  5. שלח את הבקשה

3.2 בדיקת תווי חנייה פעילים​

  1. הזן מספר זהות
  2. בחר רשות מקומית
  3. קבל רשימת תווי חנייה פעילים

3.3 קבלת סוגי תווי חנייה זמינים​

  1. בחר רשות מקומית
  2. קבל רשימת סוגי תווי חנייה זמינים

4. תיאור זרימת העבודה​

4.1 ארבעת הזרימות (Gisonim)​

זרימה 1: מהמערך לשירות תו חנייה​

מה קורה בזרימה:

  1. אימות הרשאות דרך @Roles('admin')
  2. אימות נתונים עם class-validator
  3. בדיקת תקינות פרטי הבקשה
  4. שמירת הבקשה במערכת

איזה נתונים מועברים:

  • פרטי נהג (שם, תעודת זהות, כתובת, טלפון, אימייל)
  • פרטי רכב (מספר רכב, סוג רכב, שנת ייצור)
  • פרטי בקשה (סוג תו חנייה, מסמכים מצורפים)
  • מטא-דאטה (מספר הפניה, תאריך שליחה)

איך מטופלות שגיאות:

  • שגיאות אימות מוחזרות עם הודעות בעברית
  • שגיאות שרת מוחזרות עם קוד שגיאה מתאים

מה מוחזר:

  • תווי חנייה פעילים או סוגי תווי זמינים או אישור הגשת בקשה

זרימה 2: משירות תו חנייה לספקית חיצונית​

מה קורה בזרימה:

  1. חיפוש רשות מקומית לפי קוד יישוב
  2. קבלת פרטי ספקית חיצונית מהרשות
  3. קבלת טוקן אימות מהספקית
  4. העברת נתונים מעובדים לספקית

איזה נתונים מועברים:

  • נתונים מעובדים בפורמט JSON
  • פרטי אימות (טוקן)
  • קוד רשות מקומית

איך מטופלות שגיאות:

  • שגיאות חיבור לספקית
  • שגיאות אימות
  • שגיאות העברת נתונים

מה מוחזר:

  • אישור קבלת הבקשה מהספקית

זרימה 3: מספקית חיצונית לשירות תו חנייה​

מה קורה בזרימה:

  1. עיבוד נתונים על ידי הספקית
  2. עדכון רשומות במערכת הספקית
  3. החזרת תגובה למערכת מוני serviceת

איזה נתונים מועברים:

  • סטטוס עיבוד
  • תווי חנייה פעילים
  • סוגי תווי חנייה זמינים
  • הודעות שגיאה (אם יש)

איך מטופלות שגיאות:

  • שגיאות עיבוד נתונים
  • שגיאות חיבור
  • שגיאות אימות

מה מוחזר:

  • אישור עיבוד מוצלח או הודעת שגיאה

זרימה 4: משירות תו חנייה למערך​

מה קורה בזרימה:

  1. החזרת DTO מהקונטרולר
  2. סריאליזציה אוטומטית ל-JSON על ידי NestJS
  3. שליחה למשתמש

איזה נתונים מועברים:

  • תווי חנייה פעילים (מספר רכב, תאריכי תוקף, סוג תו, אזור חנייה)
  • סוגי תווי חנייה זמינים (קוד סוג, תיאור)
  • אישור הגשת בקשה (קוד שגיאה, הודעה)

איך מטופלות שגיאות:

  • שגיאות HTTP: קודי שגיאה סטנדרטיים (400, 401, 403, 500)
  • שגיאות אימות: 401 Unauthorized
  • שגיאות נתונים: 400 Bad Request
  • שגיאות שרת: 500 Internal Server Error

מה מוחזר:

  • JSON Response עם הנתונים המבוקשים

4.2 בדיקת Directus Dummy Server​

מתי נקרא:

  • במצב פיתוח (NODE_ENV === 'development')
  • כאשר הספקית מכוונת לשרת Directus

מה נבדק:

  • תקינות חיבור לשרת Directus
  • זמינות נתונים לבדיקה
  • תקינות טוקן אימות

למה זה נדרש:

  • בדיקות במצב פיתוח
  • סימולציה של ספקיות חיצוניות
  • אימות פונקציונליות ללא ספקיות אמיתיות

איך זה משפיע על הזרימה:

  • מחליף את הספקית החיצונית האמיתית
  • מאפשר בדיקות ללא תלות בספקיות חיצוניות
  • מספק נתוני דמו לבדיקות

5. תלות חיצוניות ושירותים​

5.1 שירותים פנימיים​

  • MunicipalitiesService: ניהול רשויות מקומיות
  • SupplierAuthServiceService: אימות עם ספקיות חיצוניות
  • ErrorHandlerService: טיפול בשגיאות
  • MongodbServiceService: גישה למסד נתונים

5.2 שירותים חיצוניים​

  • Directus: שרת דמו לבדיקות
  • ספקיות מוניציפליות: עיבוד בקשות תווי חנייה

5.3 תלויות טכניות​

  • NestJS: מסגרת עבודה
  • MongoDB: מסד נתונים
  • Axios: בקשות HTTP
  • Class-validator: אימות נתונים
  • OAuth2: אימות משתמשים

6. תצורה ומשתני סביבה​

6.1 משתני סביבה נדרשים​

  • NODE_ENV: סביבת עבודה (development/production)
  • DemoProvider_url: כתובת שרת Directus
  • DemoProvider_token: טוקן אימות ל-Directus
  • mongo_conn: חיבור למסד נתונים MongoDB
  • parking_url: כתובת שירות תווי חנייה

6.2 תצורת בסיס נתונים​

  • Collection: externalsuppliers - ספקיות חיצוניות
  • Collection: municipalities - רשויות מקומיות
  • Collection: services - שירותים מוניציפליים

7. מבני נתונים / DTOs / מודלים​

7.1 DTOs עיקריים​

  • ParkingPermitRequestDto: בקשה לתו חנייה
  • ActiveParkingTicketDto: תווי חנייה פעילים
  • ExistingParkingTicketsDto: סוגי תווי חנייה זמינים
  • SubmitParkingPermitDto: תגובה להגשת בקשה
  • ParkingPersonalInformationDto: פרטי נהג
  • StepCarsDto: פרטי רכבים

7.2 סכמות MongoDB​

  • ExternalSupplier: ספקיות חיצוניות
  • Service: שירותים מוניציפליים
  • Municipality: רשויות מקומיות

8. טיפול בשגיאות ומקרי קצה​

8.1 שגיאות אימות​

  • נתונים חסרים או לא תקינים
  • פורמט תאריכים לא נכון
  • מספרי תעודת זהות לא תקינים
  • כתובות אימייל לא תקינות

8.2 שגיאות חיבור​

  • חיבור לספקית חיצונית נכשל
  • חיבור למסד נתונים נכשל
  • חיבור ל-Directus נכשל

8.3 שגיאות עסקיות​

  • רשות מקומית לא נמצאה (קוד 90)
  • רחוב לא נמצא (קוד 104)
  • קוד רשות לא נמצא (קוד 101)
  • חנייה לא נמצאה (קוד 103)

9. אבטחה והרשאות​

9.1 אימות​

  • OAuth2 Guard לכל הבקשות
  • אימות טוקן JWT
  • בדיקת הרשאות משתמש

9.2 הרשאות​

  • רק משתמשים עם תפקיד 'admin' יכולים לגשת לשירות
  • בדיקת הרשאות לפי תפקיד

9.3 הגנות​

  • אימות קלט מחמיר
  • הגנה מפני SQL Injection
  • הגנה מפני XSS

10. בדיקות​

10.1 בדיקות יחידה​

  • בדיקת DTOs עם נתונים תקינים ולא תקינים
  • בדיקת שירותי אימות
  • בדיקת טרנספורמציה של נתונים

10.2 בדיקות אינטגרציה​

  • בדיקת חיבור לספקיות חיצוניות
  • בדיקת חיבור למסד נתונים
  • בדיקת זרימת נתונים מלאה

10.3 בדיקות E2E​

  • בדיקת זרימה מלאה מהמשתמש ועד הספקית
  • בדיקת תרחישי שגיאה
  • בדיקת ביצועים

11. לוגים ומעקב​

11.1 לוגים​

  • לוגים של כל בקשה נכנסת
  • לוגים של שגיאות
  • לוגים של חיבורים לספקיות

11.2 מעקב​

  • מעקב אחר זמני תגובה
  • מעקב אחר שיעורי הצלחה
  • מעקב אחר שגיאות